<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
How do I write an ECLiPSe program?
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot011.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot008.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot013.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc12">3.4</A>&nbsp;&nbsp;How do I write an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> program?</H2><UL>
<LI><A HREF="umsroot012.html#toc2">Compiling a program</A>
<LI><A HREF="umsroot012.html#toc3">Executing a query</A>
<LI><A HREF="umsroot012.html#toc4">Editing a file</A>
<LI><A HREF="umsroot012.html#toc5">Debugging a program</A>
<LI><A HREF="umsroot012.html#toc6">Getting help</A>
<LI><A HREF="umsroot012.html#toc7">Other tools</A>
<LI><A HREF="umsroot012.html#toc8">Preference Editor</A>
</UL>

You need to use an editor to write your programs. ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> does not come
with an editor, but any editor that can save plain text files can be used.
Save your program as a plain text file, and you can then compile the
program into ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and run it.<BR>
<BR>
With TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, you can specify the editor you want to use, and this
editor will be started by TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, e.g., when you select a file in
the `Edit' option under the File menu. The default values are the value of
the VISUAL environment variable under Unix, or Wordpad under Windows.
This can be changed with the Preference Editor under the Tools menu.<BR>
<BR>
<A NAME="toc2"></A>
<H3 CLASS="subsection"><A NAME="htoc13">3.4.1</A>&nbsp;&nbsp;Compiling a program</H3>
From the <TT>File</TT> menu, select the <TT>Compile ...</TT> option.
This will bring up a file selection dialog.
Select the file you wish to compile, and click on the <TT>Open</TT> button.
This will compile the file and any others it depends on.
Messages indicating which files have been compiled and describing any errors
encountered will be displayed in the bottom portion of the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
window (<TT>Output and Error Messages</TT>).<BR>
<BR>
If a file has been modified since it was compiled,
it may be recompiled by clicking on the <TT>make</TT> button.
This recompiles any files which have become out-of-date.<BR>
<BR>
For more information on program compilation and the compiler, please see
chapter <A HREF="umsroot028.html#chapcompiler">6</A>.<BR>
<BR>
<A NAME="toc3"></A>
<H3 CLASS="subsection"><A NAME="htoc14">3.4.2</A>&nbsp;&nbsp;Executing a query</H3>
To execute a query, first enter it into the <TT>Query Entry</TT>
text field.
You will also need to specify which module the query should be run from, by
selecting the appropriate entry from the drop-down list to the left of the
<TT>Query Entry</TT> field.
Normally, the default selection of <TT>eclipse</TT> will be fine; this will
allow access to all ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> built-ins and all predicates that have not
explicitly been compiled into a different module.
Selecting another module for the query is only needed if you wish to call a
predicate which is not visible from the <TT>eclipse</TT> module, in which
case you need to select that module.
(For more information about the module system, please see chapter
<A HREF="umsroot037.html#chapmodules">7</A>.)<BR>
<BR>
To actually execute the query, either hit the <TT>Enter</TT> key while
editing the query, or click on the <TT>run</TT> button.
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> maintains a history of commands entered during the session, and
these may be recalled either by using the drop-down list to the right of the
<TT>Query Entry</TT> field, or by using the up and down arrow keys while
editing the <TT>Query Entry</TT> field.<BR>
<BR>
If ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> cannot find a solution to the query, it will print <TT>No</TT>
in the <TT>Results</TT> section of the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> window.
If it finds a solution and knows there are no more, it will print it in the
<TT>Results</TT> section, and then print <TT>Yes</TT>.
If it finds a solution and there may be more, it will print the solution
found as before, print <TT>More</TT>, and enable the <TT>more</TT> button.
Clicking on the <TT>more</TT> button tells ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to try to find
another solution.
In all cases it also prints the total time taken to execute the query.<BR>
<BR>
Note that a query can be interrupted during execution by clicking on the
<TT>interrupt</TT> button.<BR>
<BR>
<A NAME="toc4"></A>
<H3 CLASS="subsection"><A NAME="htoc15">3.4.3</A>&nbsp;&nbsp;Editing a file</H3>
<A NAME="secedit"></A>
If you wish to edit a file (e.g., a program source file), then you may do so
by selecting the <TT>Edit ...</TT> option from the <TT>File</TT> menu.
This will bring up a file selection dialog.
Select the file you wish to edit, and click on the <TT>Open</TT> button.<BR>
<BR>
When you have finished editing the file, save it.
After you've saved it, if you wish to update the version compiled into
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> (assuming it had been compiled previously), simply click on the
<TT>make</TT> button.<BR>
<BR>
You can change which program is used to edit your file by using the
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Preference Editor, available from the <TT>Tools</TT> menu.<BR>
<BR>
<A NAME="toc5"></A>
<H3 CLASS="subsection"><A NAME="htoc16">3.4.4</A>&nbsp;&nbsp;Debugging a program</H3>
<A NAME="secdebug"></A>
To help diagnose problems in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> programs, TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> provides the
tracer.
This can be invoked by selecting the <TT>Tracer</TT> option from the
<TT>Tools</TT> menu.
The next time a goal is executed, the tracer window will become active,
allowing you to step through the program's execution and examine the
program's state as it executes.<BR>
<BR>
The tracer displays the current call stack and a trace log.
By using the left mouse button in the <TT>Call Stack</TT> region of the
tracer window, you can bring up a menu of additional operations you can
perform on that goal, such as inspecting it, or setting a spy point on the
predicate in question.
Selecting <TT>Configure filter ...</TT> from the <TT>Options</TT> menu
of the tracer will launch the conditional filter.
This filter allows you to
specify conditions on which the tracer should stop at a debug port. This
can be very useful for skipping over unwanted debug ports.<BR>
<BR>
For more information on using the tracer, please see the online help,
available by selecting <TT>Tracer Help</TT> from the <TT>Help</TT> menu.<BR>
<BR>
Other TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> tools which are useful while using the tracer are:
<UL CLASS="itemize"><LI CLASS="li-itemize">the predicate browser (available by selecting the <TT>Predicate
Browser</TT> option from the <TT>Tools</TT> menu), which is useful for setting
or removing spy points on predicates, or for setting the
<B>start_tracing</B>
flag which activates the tracer when a particular predicate is called for
the first time; and<BR>
<BR>
<LI CLASS="li-itemize">the term inspector (available by double left clicking on a term from
the stack window, or by selecting the <TT>Inspector</TT>
option from the <TT>Tools</TT> menu), which is useful for examining and
browse the arguments of a term in detail.<BR>
<BR>
<LI CLASS="li-itemize">the delayed goals browser (available by selecting the <TT>Delayed
Goals</TT> option from the <TT>Tools</TT> menu), which allows you to inspect
the current list of delayed goals.<BR>
<BR>
<LI CLASS="li-itemize">the display matrix (available either from calls in user's code, or by
interactively selecting terms to be observed from the inspector, tracer or
delay goals tools), which allows you to monitor any changes to a term and
its arguments.</UL>
More information about debugging in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> may be found in chapter
<A HREF="umsroot074.html#chapdebug">14</A>.<BR>
<BR>
<A NAME="toc6"></A>
<H3 CLASS="subsection"><A NAME="htoc17">3.4.5</A>&nbsp;&nbsp;Getting help</H3>
More detailed help than is provided here can be obtained online for all
the features of TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.
Simply select the entry from the <TT>Help</TT> menu on TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>'s
top-level window which corresponds to the topic or tool you are interested
in.<BR>
<BR>
<A NAME="toc7"></A>
<H3 CLASS="subsection"><A NAME="htoc18">3.4.6</A>&nbsp;&nbsp;Other tools</H3>
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> comes with a number of useful tools.
Some have been mentioned above, but here is a more complete list.
Note that we only provide brief descriptions here; for more details, please
see the online help for the tool in question.<BR>
<BR>

<H4 CLASS="subsubsection">Compile scratch-pad</H4>
This tool allows you to enter small amounts of program code and have it
compiled.
This is useful for quick experimentation, but not for larger examples or
programs you wish to keep, since the source code is lost when the session is
exited.<BR>
<BR>

<H4 CLASS="subsubsection">Source File Manager</H4>
This tool allows you to keep track of and manage which source files have
been compiled in the current ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session.
You can select files to edit them, or compile them individually, as well as
adding new files.<BR>
<BR>

<H4 CLASS="subsubsection">Predicate Browser</H4>
This tool allows you to browse through the modules and predicates which have
been compiled in the current session.
It also lets you alter some properties of compiled predicates.<BR>
<BR>

<H4 CLASS="subsubsection">Source Viewer</H4>
This tool attempts to display the source code for predicates selected in
other tools.<BR>
<BR>

<H4 CLASS="subsubsection">Delayed Goals</H4>
This tool displays the current delayed goals, as well as allowing a spy
point to be placed on the predicate and the source code viewed.<BR>
<BR>

<H4 CLASS="subsubsection">Tracer</H4>
As discussed in section <A HREF="#secdebug">3.4.4</A>, the tracer is useful for debugging
programs.
See also chapter <A HREF="umsroot074.html#chapdebug">14</A>.<BR>
<BR>

<H4 CLASS="subsubsection">Inspector</H4>
This tool provides a graphical browser for inspecting terms.
Goals and data terms are displayed as a tree structure.
Sub-trees can be collapsed and expanded by double-clicking.
A navigation panel can be launched which provides arrow buttons as an
alternative way to navigate the tree.<BR>
<BR>
Note that while the inspector window is open, interaction with other
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> windows is disallowed.
This prevents the term from changing while being inspected.
To continue TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, the inspector window must be closed.<BR>
<BR>

<H4 CLASS="subsubsection">Global Settings</H4>
This tool allows the setting of some global flags governing the way
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> behaves.
See also the documentation for the
<A HREF="../bips/kernel/env/set_flag-2.html"><B>set_flag/2</B></A><A NAME="@default91"></A> and
<A HREF="../bips/kernel/env/get_flag-2.html"><B>get_flag/2</B></A><A NAME="@default92"></A> predicates.<BR>
<BR>

<H4 CLASS="subsubsection">Statistics</H4>
This tool displays some statistics about memory and CPU usage of the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> system, updated at regular intervals.
See also the documentation for the
<A HREF="../bips/kernel/env/statistics-0.html"><B>statistics/0</B></A><A NAME="@default93"></A> and
<A HREF="../bips/kernel/env/statistics-2.html"><B>statistics/2</B></A><A NAME="@default94"></A> predicates.<BR>
<BR>

<H4 CLASS="subsubsection">Simple Query</H4>
This tool allows the user to send a simple query to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> even while
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is running some program and the Toplevel Query Entry window
is unavailable.
Note that the reply is shown in EXDR format (see the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Embedding
and Interfacing Manual).<BR>
<BR>

<H4 CLASS="subsubsection">Library Help</H4>
This tool allows you to browse the online help for the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> libraries.
On the left is a tree display of the libraries available and the predicates
they provide.
<UL CLASS="itemize"><LI CLASS="li-itemize">
Double clicking on a node in this tree either expands it or collapses it
again.
<LI CLASS="li-itemize">Clicking on an entry displays help for that entry to the right.
<LI CLASS="li-itemize">Double clicking on a word in the right-hand pane searches for help
entries containing that string.
</UL>
You can also enter a search string or a predicate specification manually
in the text entry box at the top right.
If there is only one match, detailed help for that predicate is displayed.
If there are multiple matches, only very brief help is displayed for each;
to get detailed help, try specifying the module and/or the arity of the
predicate in the text field.<BR>
<BR>
<A NAME="toc8"></A>
<H3 CLASS="subsection"><A NAME="htoc19">3.4.7</A>&nbsp;&nbsp;Preference Editor</H3>
This tool allows you to edit and set various user preferences. This include
parameters for how TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will start up, e.g., the amount of memory it
will be able to use, and an initial query to execute; and parameters which
affects the appearance of TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, such as the fonts TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
uses.<BR>
<BR>
<HR>
<A HREF="umsroot011.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot008.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot013.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
